Usenet 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / unix / volume11 / templates / part01 next >

Wrap

Internet Message Format | 1987-10-04 | 50.7 KB

Subject: v11i091: Template-mode for GNU Emacs, Part01/06 Newsgroups: comp.sources.unix Sender: sources Approved: rs@uunet.UU.NET Submitted-by: "Mark A. Ardis" <maa@sei.cmu.edu> Posting-number: Volume 11, Issue 91 Archive-name: templates/part01 This is the first of six pieces of "template-mode", a minor mode for GNU Emacs. Template-mode supports the creation and manipulation of templates of text. Templates are useful for boilerplate, idioms, or anything structural that has concrete syntax. Included in this package are templates for C, LaTeX, Pascal, Scribe, and a few other miscellaneous languages. My biggest regret in distributing template-mode is that it has not been adequately tested. It works fine for me, but I have not been able to generate large test scripts for it, yet. I expect to continue to work on this package at my new location. Please send comments, suggestions, bugs, etc. to: maa@sei.cmu.edu or Mark A. Ardis Software Engineering Institute 4500 Fifth Avenue Pittsburgh, PA 15213 #! /bin/sh # This is a shell archive, meaning: # 1. Remove everything above the #! /bin/sh line. # 2. Save the resulting text in a file. # 3. Execute the file with /bin/sh (not csh) to create: # MANIFEST # README # INSTALL # dir # manual.texinfo # template.texinfo export PATH; PATH=/bin:/usr/bin:$PATH echo shar: "extracting 'MANIFEST'" '(1599 characters)' if test -f 'MANIFEST' then echo shar: "will not over-write existing file 'MANIFEST'" else sed 's/^X//' << \SHAR_EOF > 'MANIFEST' XFile Archive Description X---- ------- ----------- X XINSTALL 1 How to get started XMANIFEST 1 This shipping list XREADME 1 Description of files Xawk.el 5 Major mode for awk Xawk.tpl 6 Templates for awk Xbib.el 5 Major mode for bibliographies Xbib.tpl 6 Templates for bibliographies Xc.tpl 6 Templates for C Xdir 1 New entry for Info menu Xelisp.tpl 6 Templates for Emacs Lisp Xgeneric.tpl 6 Generic templates (always available) Xlatex.tpl 6 Templates for LaTeX Xmanual.texinfo 1 TeX wrapper for user manual Xmenu.el 5 Template-mode -- selection of entries Xpascal.el 5 Major mode for Pascal Xpascal.tpl 6 Templates for Pascal Xscribe.tpl 6 Templates for Scribe Xsymbol.el 5 Template-mode -- insertion-in-place Xtemplate.el 2 Root of template-mode Xtemplate.texinfo 1 User manual Xtexinfo.tpl 6 Templates for Texinfo Xtplhelper.el 3 Template-mode -- non-interactive functions Xtplparse.el 4 Template-mode -- parser Xtplreplace.el 5 Template-mode -- replacement functions Xtplscan.el 4 Template-mode -- scanner and unscanner Xtplvars.el 2 Template-mode -- global variables SHAR_EOF if test 1599 -ne "`wc -c < 'MANIFEST'`" then echo shar: "error transmitting 'MANIFEST'" '(should have been 1599 characters)' fi fi echo shar: "extracting 'README'" '(1417 characters)' if test -f 'README' then echo shar: "will not over-write existing file 'README'" else sed 's/^X//' << \SHAR_EOF > 'README' XThis directory contains the code, data files and documentation for Xtemplate-mode, a minor mode of GNU Emacs. The files ending with ".el" Xare GNU Emacs Lisp files. Files ending with ".texinfo" are TeX source Xfiles and Gnuemacs info source files. Files ending with ".tpl" are Xsource-form template files. X Xawk.el Major mode for editing "awk" programs Xbib.el Major mode for editing bibliography files Xmenu.el Template-mode -- major mode for selections Xpascal.el Major mode for editing Pascal programs Xsymbol.el Template-mode -- major mode for entry-in-place Xtemplate.el Root of template-mode Xtplhelper.el Template-mode -- non-interactive functions Xtplparse.el Template-mode -- Parsing and unparsing functions Xtplreplace.el Template-mode -- replacement functions Xtplscan.el Template-mode -- scanner and unscanner functions Xtplvars.el Template-mode -- global variables and options Xdir New part of root directory for Info Xmanual.texinfo User manual source -- printed form wrapper Xtemplate.texinfo User manual source -- bulk of document Xawk.tpl Templates for awk programs Xbib.tpl Templates for bibliography files Xc.tpl Templates for C-mode Xelisp.tpl Templates for Emacs-lisp-mode Xgeneric.tpl Templates for use in any mode---mostly Function type Xlatex.tpl Templates for LaTeX-mode Xpascal.tpl Templates for Pascal-mode Xscribe.tpl Templates for Scribe-mode Xtexinfo.tpl Templates for Texinfo-mode SHAR_EOF if test 1417 -ne "`wc -c < 'README'`" then echo shar: "error transmitting 'README'" '(should have been 1417 characters)' fi fi echo shar: "extracting 'INSTALL'" '(1958 characters)' if test -f 'INSTALL' then echo shar: "will not over-write existing file 'INSTALL'" else sed 's/^X//' << \SHAR_EOF > 'INSTALL' XThis file describes how to install template-mode, a minor mode of GNU XEmacs. X X1) Decide where you want to put the template files. These are data Xfiles that define the form and content of templates. Users will Xprobably want to know where they are, even if all of the load paths Xare set correctly. For the purposes of this description, let us call Xthe directory containing the templates "TEMPLATES". X X2) Find the variable "tpl-load-path" in "tplvars.el" and change its Xdefault value to: X X (list nil "TEMPLATES") X X(The "nil" stands for "default directory", similarly to "load-path".) X X3) Put the template-mode code files ("*.el") in the standard GNU XEmacs Lisp directory. (The main problem you want to avoid is failure Xto "autoload" files.) X X4) Go to a buffer in "Fundamental" mode. (Actually, any buffer will Xdo, but this avoids loading some templates twice.) X X5) (load "template.el") -- If you see any messages about missing Xproperties, then check to make sure that all of the files were loaded. X(The beginning of "template.el" contains a list of "requires".) Once Xyou are satisfied that everything can be "autoloaded", you can X"byte-compile" all of the source code files. X X6) (template-mode) -- You should see a message to the effect that no Xtemplates were found for this mode, and the symbol "Template" should Xappear in the mode line. X X7) (tpl-recompile-templates) -- This function compiles templates for Xseveral different modes. It is not necessary, but will significantly Xspeed-up loading of standard templates. X X8) (find-file "template.texinfo") X X9) (texinfo-format-buffer) -- Save the results in X"INFOROOT/template", where "INFOROOT" is the directory containing the XInfo nodes for GNU Emacs. X X10) Add the menu entry for template-mode found in "dir" to the Xtop-level menu of the "Info" tree. X XYou don't have to compile anything to start using the package. (In Xfact, you can stop at step 6.) See the user manual for a tutorial. SHAR_EOF if test 1958 -ne "`wc -c < 'INSTALL'`" then echo shar: "error transmitting 'INSTALL'" '(should have been 1958 characters)' fi fi echo shar: "extracting 'dir'" '(171 characters)' if test -f 'dir' then echo shar: "will not over-write existing file 'dir'" else sed 's/^X//' << \SHAR_EOF > 'dir' X X* template: (template). X Template-mode provides commands for creating and X manipulating "templates"---rectangular regions that X correspond to grammatical productions. SHAR_EOF if test 171 -ne "`wc -c < 'dir'`" then echo shar: "error transmitting 'dir'" '(should have been 171 characters)' fi fi echo shar: "extracting 'manual.texinfo'" '(665 characters)' if test -f 'manual.texinfo' then echo shar: "will not over-write existing file 'manual.texinfo'" else sed 's/^X//' << \SHAR_EOF > 'manual.texinfo' X\input texinfo @c -*-texinfo-*- X@settitle Template-Mode for GNU Emacs X X@titlepage X@sp 10 X@center @titlefont{Template-Mode for GNU Emacs} X@sp 3 X@center Mark A. Ardis X@sp 1 X@center Wang Institute of Graduate Studies X@center Tyngsboro, Massachusetts 01879 X@sp 1 X@center July 31, 1987 X@sp 3 X@center @b{Abstract} XThis manual describes @i{template-mode}: a set of functions for Xmanipulating templates of text within GNU Emacs. Some of the commands Xinsert and expand templates, while others help you create templates for Xlater (or immediate) use. X@end titlepage X X@c Include files with actual text X@include template.texinfo X X@c Print the table of contents X@contents X X@bye SHAR_EOF if test 665 -ne "`wc -c < 'manual.texinfo'`" then echo shar: "error transmitting 'manual.texinfo'" '(should have been 665 characters)' fi fi echo shar: "extracting 'template.texinfo'" '(41381 characters)' if test -f 'template.texinfo' then echo shar: "will not over-write existing file 'template.texinfo'" else sed 's/^X//' << \SHAR_EOF > 'template.texinfo' X@setfilename template X X@node top, tutorial, (dir), (dir) X@chapter Introduction to Template-Mode X X@dfn{Template-mode} provides commands for inserting and manipulating text. XIt is particularly useful for inserting standard fragments, such as Xboilerplate for documents or function headers for programs. There are Xtemplates for major program fragments of C, Emacs-Lisp, and Pascal, as well as Xstandard boilerplate for Scribe and @TeX{} documents. X XThe chapter titled ``Tutorial'' explains how to invoke @i{template-mode}, Xand gives a small example. The ``Commands'' chapter serves as a reference Xmanual for @i{template-mode} commands. Options and hooks for modifying the Xbehavior and appearance of templates are discussed in ``Customization''. XThe ``Details'' chapter describes the precise syntax of templates and Xplaceholders. Finally, the appendices contain excerpts from the template Xdefinition files. X XThe simplest form of templates are rectangular blocks of text. Some Xtemplates have @dfn{placeholders} within them. A placeholder may be Xreplaced by any object of its type. For example, @dfn{text} type Xplaceholders may be replaced by any text string that does not contain a Xnewline. Some templates are menu lists of other templates---you must Xselect one of the items of the list to insert. Another form of template Xgenerates a sequence of some other template---you are asked when to stop Xgenerating. X XIn fact, a set of templates defines a context-free grammar. Each X@dfn{Sequence} template is a production. Placeholders represent Xnonterminals. The act of inserting and expanding a template is the same as Xbuilding the derivation tree for the nonterminal on the left side of the Xproduction. @dfn{Selection} templates represent nonterminals with more Xthan one production. @dfn{Repetition} templates represent productions of Xthe form @samp{B(AB)*}, where @samp{A} is any terminal string and @samp{B} Xis any nonterminal. There are three more types of templates: X@dfn{Lexical}, @dfn{String} and @dfn{Function}. Lexical templates are used Xto describe symbols by regular expressions. String templates are a special Xcase of Sequence templates that contain no placeholders (and are parsed Xfaster). Function templates provide a mechanism for invoking any XEmacs-Lisp function during template expansion. X XTemplates are defined by a simple syntax and stored in ASCII files. The Xstandard templates for use by @i{template-mode} may be found in a directory Xreferenced by @file{tpl-load-path}. Files ending with @file{.tpl} are Xtemplate source files. Compiled versions are found in files ending with X@file{tpl.elc}. You may find it useful to print the @file{.tpl} files for Xthe languages you use. X X@menu X* tutorial:: A short example. X* commands:: How to use templates while editing. X* customization:: How to tailor templates and their commands. X* details:: Details of template and placeholder syntax X@end menu X X@node tutorial, commands, top, top X@chapter Tutorial -- A Short Example X XIn the example below, the following conventions have been used: X@itemize @bullet X@item XThe first line shows a prompt, or contains @samp{(No prompt)} to show the Xabsence of prompting. X X@item XThe second, indented line shows your response. If a carriage return X(@key{RET}) is required, it will be included in your response. X@end itemize XThe Appendices contain the templates described in this example. X XFirst, visit @file{sample.el}, and make sure that @i{Emacs-Lisp-Mode} is in Xeffect. X X@table @code X@item (No prompt) X@key{ESC} x X X@item M-x X@* Xload-file @key{RET} X X@item Load file: X@* Xtemplate @key{RET} X X@item (No prompt) X@key{ESC} x X X@item M-x X@* Xtemplate-mode @key{RET} X@end table X XAt this point, @i{template-mode} will be initialized. Completion of Xinitialization is signalled by the presence of the symbol @code{Template} Xin the mode line. If Emacs complains about not finding @file{template}, Xthen you will need to find the absolute path name for this package. (See Xyour computer center or a knowledgeable Emacs user.) X XYou may want to experiment with the template-generation commands at this Xpoint, or continue the tutorial on the next page. X X@page X X@table @code X@item (No prompt) X@ctrl{c} @ctrl{t} t X X@item generate-template: Name of template? Xpackage @key{RET} X X@item Expand? (y or n) Xy X X@item Expand? (y or n) Xy X X@item Replace <text:documentation> with what? XSample package @key{RET} X X@item Expand? (y or n) Xn X X@item Expand? (y or n) Xn X X@item Keep optional placeholder? (y or n) Xy X X@item Expand? (y or n) Xn X X@item Expand? (y or n) Xy X X@item Expand? (y or n) Xy X X@item Replace <textenter:function-name> with what? Xreverse @key{RET} X X@item Expand? (y or n) Xy X X@item Replace <text:arguments> with what? Xlist @key{RET} X X@item Expand? (y or n) Xy X X@item Type replacement and exit with @key{ESC}-@ctrl{c}. XReverse the items in LIST. @key{ESC}-@ctrl{c} X X@item Expand? (y or n) Xy X X@item Position on selection and exit with Return (or @key{ESC}-@ctrl{c}). Xx @key{RET} X X@item Expand? (y or n) Xy X X@item Replace <text:local-variables> with what? Xitem @key{RET} X X@item Expand? (y or n) Xy X X@item Position on selection and exit with Return (or @key{ESC}-@ctrl{c}). Xw @key{SPC} @key{RET} X X@item Expand? (y or n) Xy X X@item Replace <text:list> with what? Xlist @key{RET} X X@item Expand? (y or n) Xy X X@item Replace <text:item> with what? Xitem @key{RET} X X@item More instances of functions? (y or n) Xn X X@item Done. X...(You may finish this function now or continue)... X X@item (No prompt) X@ctrl{c} @ctrl{t} @ctrl{p} X X@item (No prompt) X@ctrl{c} @ctrl{t} @ctrl{k} X X@item (No prompt) X@key{ESC} < X X@item Mark set X@* X@ctrl{c} @ctrl{t} @ctrl{e} X X@item Expand? (y or n) Xy X X@item Expand? (y or n) Xy X@end table X@page X XFor a shorter (i.e., fewer keystrokes) incantation of this example, try Xsetting two options: X@table @code X@item tpl-keep-optional-placeholders XSetting this to @code{nil} will automatically delete optional placeholders Xin templates. X X@item tpl-ask-expansion-depth XSetting this to @code{4} will automatically begin expansion of Xplaceholders, until the depth of recursive expansions reaches 4. X@end table X@noindent XExpanding the @code{package} template should take fewer keystrokes after Xthese changes. X X@node commands, customization, tutorial, top X@chapter Commands -- How to Use Templates While Editing X XThis chapter serves as a reference to all of the @i{template-mode} commands. XThe first section briefly describes each command. Following sections cover Xcommands by topic, such as selecting or expanding templates. X X@menu X* summary:: Short description of all the commands. X* loading:: Initialization of template-mode. X* selecting:: Choosing the right template. X* expanding:: Replacing placeholders by templates or text. X* menus:: Selection of choices -- Menu-Mode. X* symbols:: Short expressions as parameters to templates. X* textlong:: Large blocks of text as parameters to templates. X* wrapping:: Weak parsing to manipulate enclosing templates. X* searching:: Finding and replacing template instances. X* aborting:: How to stop or quit. X* creating:: How to create your own templates. X@end menu X X@node summary, loading, commands, commands X@section Summary -- Short description of all the commands X XHere is a short description of all of the @i{template-mode} commands: X X@table @code X@item add-symbol (@ctrl{c} @ctrl{t} a) XAdd the symbol before point to the list of symbols created by X@i{textenter} placeholders. X X@item compile-templates (unbound) XStore the templates in a form that allows faster loading. X X@item delete-placeholder (@ctrl{c} @ctrl{t} @ctrl{k}) XDelete the placeholder at point. X X@item describe-template-mode (@ctrl{c} @ctrl{t} @ctrl{h}) XGive a brief description of template-mode. X X@item expand-placeholder (@ctrl{c} @ctrl{t} e) XExpands the placeholder at point with its template description. X X@item expand-placeholders-in-region (@ctrl{c} @ctrl{t} @ctrl{e}) XExpands all placeholders in the region with their template descriptions. X X@item expand-symbol (@ctrl{c} @ctrl{t} @key{TAB}) XExpand the symbol before point using the list of symbols created by X@i{textenter} placeholders. X X@item generate-any-template (@ctrl{c} @ctrl{t} ?) XBuilds a list of all the templates available, and waits for selection. X X@item generate-template (@ctrl{c} @ctrl{t} t) XPrompts for the name of a template and then inserts it at point. XPlaceholders within the template are expanded interactively. X X@item load-tpl-buffer (unbound) XAdd a new buffer of templates to the working set. (Only understands text Xform of templates. Uses standard buffer name completion, with default X@file{new.tpl}.) X X@item load-tpl-file (unbound) XAdd a new file of templates to the working set. (Only understands text Xform of templates, and uses standard file name completion.) X X@item load-tpl-library (unbound) XAdd a new file of templates to the working set. (Understands both text and Xcompiled forms of templates, and uses the @i{tpl-load-path} variable to Xfind the file.) X X@item looking-at-tpl (unbound) XReturns @i{true} if the named template follows point. X X@item next-placeholder (@ctrl{c} @ctrl{t} @ctrl{n}) XMove to the beginning of the next placeholder. X X@item previous-placeholder (@ctrl{c} @ctrl{t} @ctrl{p}) XMove to the beginning of the previous placeholder. X X@item query-replace-groups (@ctrl{c} @ctrl{t} g) XReplace instances of groups of lines (matched by regular expressions) with Xplaceholders. X X@item query-replace-lines (@ctrl{c} @ctrl{t} l) XReplace lines with placeholders. X X@item query-replace-tpl (unbound) XReplace instances of one template with corresponding instances of another. X X@item region-to-tpl (unbound) XDefine a template, using the current region of text. X X@item replace-line-with-placeholder (@ctrl{c} @ctrl{t} r) XReplace the current line with a placeholder. X X@item replace-region-with-placeholder (@ctrl{c} @ctrl{t} @ctrl{r}) XReplace the current region with a placeholder. X X@item replace-tpl (unbound) XReplace one instance of a template with a corresponding instance of another. X X@item rewrap-template-around-point (@ctrl{c} @ctrl{t} @ctrl{u}) XUnwrap and then wrap. (See those two commands.) X X@item search-forward-tpl (unbound) XSearch for an instance of a template. X X@item template-mode (unbound) XTurns @i{template-mode} on and off. X X@item unwrap-template-around-point (@ctrl{c} @ctrl{t} u) XFind the nearest enclosing instance of the named template and remove it, Xkeeping the text that matches its destination placeholder. X X@item wrap-template-around-line (@ctrl{c} @ctrl{t} W) XUse the current line to replace the destination placeholder of a Xplaceholder. X X@item wrap-template-around-region (@ctrl{c} @ctrl{t} @ctrl{w}) XUse the current region to replace the destination placeholder of a Xplaceholder. X X@item wrap-template-around-word (@ctrl{c} @ctrl{t} w) XUse the current word to replace the destination placeholder of a Xplaceholder. X@end table X X@node loading, selecting, summary, commands X@section Loading templates -- initialization of template-mode X X@table @code X@item load-tpl-buffer (unbound) XAdd a new buffer of templates to the working set. (Only understands text Xform of templates. Uses standard buffer name completion, with default X@file{new.tpl}.) X X@item load-tpl-file (unbound) XAdd a new file of templates to the working set. (Only understands text Xform of templates, and uses standard file name completion.) X X@item load-tpl-library (unbound) XAdd a new file of templates to the working set. (Understands both text and Xcompiled forms of templates, and uses the @i{tpl-load-path} variable to Xfind the file.) X@end table X XBefore a template may be used, it must be loaded. Standard templates are Xloaded by checking the major mode of the current buffer. (E.g., the X@file{ctpl.elc} file is loaded if the major mode is ``C''.) You may load as Xmany template files as you wish, in as many buffers as you wish. Each X@i{template-mode} buffer has its own set of template files. Since many Xtemplate files use similar names for templates (e.g., @samp{stmt} occurs in Xmost), it is probably a good idea to start with only the standard template Xfiles at first. X XAlthough templates are created as text, they are converted into an internal XLisp structure when they are loaded. This conversion process may be saved Xby compiling the templates and storing the compiled form. The X@b{load-tpl-library} command is capable of reading these compiled forms, Xwhich is a faster method than reading the ASCII text forms. The X@b{load-tpl-file} and @b{load-tpl-buffer} commands only understand ASCII Xtext forms. Also, @b{load-tpl-library} uses the value of @b{tpl-load-path} Xto find the file, whereas @b{load-tpl-file} and @b{load-tpl-buffer} use Xstandard name completion. X X@node selecting, expanding, loading, commands X@section Selecting templates -- choosing the right template X X@table @code X@item generate-any-template (@ctrl{c} @ctrl{t} ?) XBuilds a list of all the templates available, and waits for selection. X X@item generate-template (@ctrl{c} @ctrl{t} t) XPrompts for the name of a template and then inserts it at point. XPlaceholders within the template are expanded interactively. X@end table X XThe @b{generate-any-template} (@ctrl{c} @ctrl{t} ?) command builds a list Xof all the available templates and waits for a selection. Since the list Xmay be quite long, it is probably best to select via the unique-prefix Xmethod: Type enough of the beginning of a template name to uniquely Xidentify it. Point will be positioned as if an incremental search were Xbeing performed. Typing a @key{RET} will select an entry. Once the Xselection has been made, generation proceeds by inserting a placeholder and Xexpanding it. X XThe @b{generate-template} (@ctrl{c} @ctrl{t} t) command requests the name Xof a template to insert and expand. Unambiguous prefixes may be completed Xwith the @key{TAB} key. If no such template exists, you will get an error Xmessage, and an error result. Otherwise, a placeholder for the requested Xtemplate will be inserted and expansion will begin. X X@node expanding, menus, selecting, commands X@section Expanding templates -- replacing placeholders by templates X X@table @code X@item delete-placeholder (@ctrl{c} @ctrl{t} @ctrl{k}) XDelete the placeholder at point. X X@item expand-placeholder (@ctrl{c} @ctrl{t} e) XExpands the placeholder at point with its template description. X X@item expand-placeholders-in-region (@ctrl{c} @ctrl{t} @ctrl{e}) XExpands all placeholders in the region with their template descriptions. X X@item next-placeholder (@ctrl{c} @ctrl{t} @ctrl{n}) XMove to the beginning of the next placeholder. X X@item previous-placeholder (@ctrl{c} @ctrl{t} @ctrl{p}) XMove to the beginning of the previous placeholder. X@end table X XExpansion of a placeholder consists of: X@enumerate X@item XFinding the appropriate template. X@item XInserting the template in place of the placeholder. X@item XDetermining the appropriate final destination of @i{point} X(including removing all destination placeholders). X@item XRecursively expanding each placeholder within the new text. X@item XLeaving @i{point} at the appropriate final destination. X@end enumerate XYou may choose not to expand any placeholder, in which case it is left Xas-is in the buffer. The command @b{expand-placeholder} (@ctrl{c} @ctrl{t} Xe) may be used to expand the placeholder at the current location of point. XThe commands @b{next-placeholder} (@ctrl{c} @ctrl{t} @ctrl{n}), X@b{previous-placeholder} (@ctrl{c} @ctrl{t} @ctrl{p}), and X@b{delete-placeholder} (@ctrl{c} @ctrl{t} @ctrl{k}) are also useful when Xcleaning up unexpanded placeholders. @b{Expand-placeholders-in-region} X(@ctrl{c} @ctrl{t} @ctrl{e}) will expand all of the placeholders in a Xregion, recursively. X XPlaceholders may be optional or required. An optional placeholder has an Xextra @samp{#} character at the beginning of its type name. When expanding Xa template containing an optional placeholder you are asked whether you Xwish to keep the placeholder. If you respond negatively, the placeholder Xis deleted. If you respond positively, the placeholder is changed into a Xrequired placeholder (i.e., the extra @samp{#} is removed). For each Xrequired placeholder you are asked if you wish to expand it. X XThe type of a placeholder (the part before the @samp{:}) may be a template Xname, one of the @dfn{text} types (@dfn{text}, @dfn{textenter} or X@dfn{textlong}), or the special @dfn{destination} type. Expansion of X@i{text} type placeholders is discussed in a later section. If the type is Xa template name, that template will be inserted in place of the Xplaceholder, and each of its placeholders will be expanded. (If the Xtemplate cannot be found an error will result.) Destination placeholders Xare removed after inserting the containing template. They are used to Xselect the final destination of @i{point}. (The location of the first Xdestination placeholder is used if at least one such placeholder is found, Xotherwise the end of the template is used for the final destination.) XNotice that expansion of placeholders and templates can be nested. X X@node menus, symbols, expanding, commands X@section Menu-mode -- selection of choices X XIf the template you request is of type @dfn{selection}, a menu will be Xconstructed in a separate window, and you will be asked to pick one of the Xentries. You may move about in this window with any of the normal movement Xcommands, but you will be prevented from modifying the buffer. The X@key{SPC} key advances to the next line. Alphabetic characters invoke an Xincremental search that is anchored at the left side of the line. Thus, Xyou may go to a particular entry by typing an unambiguous prefix of that Xentry. X XTo exit the menu type a @key{RET}. (Actually, @b{exit-recursive-edit} will Xwork, also.) If you do not like any of the choices, type a @ctrl{g} to Xabort the command. You can use @b{advertised-undo} to clean up. X X@node symbols, textlong, menus, commands X@section Symbol-mode -- short expressions as parameters to templates X X@table @code X@item add-symbol (@ctrl{c} @ctrl{t} a) XAdd the symbol before point to the list of symbols created by X@i{textenter} placeholders. X X@item expand-symbol (@ctrl{c} @ctrl{t} @key{TAB}) XExpand the symbol before point using the list of symbols created by X@i{textenter} placeholders. X@end table X XExpansion of a @i{text} placeholder is accomplished by insertion-in-place. XIn fact, a special mode is used for this, which restricts text modification Xcommands to operate within a single line. The @key{TAB} key is used to Xinvoke completion. It works similarly to command completion, except that Xit uses an identifier table constructed by @i{textenter} placeholder Xexpansions. A newline finishes the entry and exits the mode. Once the Xvalue of a @i{text} placeholder has been completed, every identical Xplaceholder within the current template expansion is replaced by this Xvalue. X XExpansion of a @i{textenter} placeholder is the same as for @i{text}, Xexcept that the entry is saved in the identifier table when it is Xcompleted. XYou may add entries to this table with the @b{add-symbol} Xcommand (@ctrl{c} a)---it adds Xthe symbol before point to the table. X@b{Expand-symbol} (@ctrl{c} @key{TAB}) expands Xpartial symbols using this table. X X@node textlong, wrapping, symbols, commands X@section Textlong -- large blocks of text as parameters to templates X XExpansion of a @dfn{textlong} placeholder creates a separate window for Xcreation of the entry. You must use @b{exit-recursive-edit} (@key{ESC} X@ctrl{c}) to complete the entry and return to the original buffer. X X@node wrapping, searching, textlong, commands X@section Wrapping -- weak parsing to manipulate enclosing templates X X@table @code X@item rewrap-template-around-point (@ctrl{c} @ctrl{t} @ctrl{u}) XUnwrap and then wrap. (See those two commands.) X X@item unwrap-template-around-point (@ctrl{c} @ctrl{t} u) XFind the nearest enclosing instance of the named template and remove it, Xkeeping the text that matches its destination placeholder. X X@item wrap-template-around-line (@ctrl{c} @ctrl{t} W) XUse the current line to replace the destination placeholder of a Xplaceholder. X X@item wrap-template-around-region (@ctrl{c} @ctrl{t} @ctrl{w}) XUse the current region to replace the destination placeholder of a Xplaceholder. X X@item wrap-template-around-word (@ctrl{c} @ctrl{t} w) XUse the current word to replace the destination placeholder of a Xplaceholder. X@end table X XThe wrap and unwrap commands provide a weak form of parsing that arises Xoften: the recognition of enclosing templates. For example, many document Xprocessors require begin/end pairs of commands or delimiters to change the Xnature of processing within a region. These pairs are easily encoded as Xtemplates, with an empty middle part represented by a destination Xplaceholder. This form of template is called a @dfn{wrapper}. X XTo wrap a region of text, use any of the commands: X@b{wrap-template-around-line} (@ctrl{c} @ctrl{t} W), X@b{wrap-template-around-region} (@ctrl{c} @ctrl{t} @ctrl{w}), or X@b{wrap-template-around-word} (@ctrl{c} @ctrl{t} w). The line and word Xforms take a prefix argument of the number of lines or words (default = 1). XTo unwrap a region of text, use the @b{unwrap-template-around-point} X(@ctrl{c} @ctrl{t} u) command. Note that this command tries to understand Xindentation, but may guess incorrectly. The X@b{rewrap-template-around-point} (@ctrl{c} @ctrl{t} @ctrl{u}) command Xcombines unwrapping with wrapping a region. It is particularly useful when Xediting existing text to change the formatting style. X X@node searching, aborting, wrapping, commands X@section Searching -- finding and replacing template instances X X@table @code X@item looking-at-tpl (unbound) XReturns @i{true} if the named template follows point. X X@item search-forward-tpl (unbound) XFind the next occurrence of a template. X X@item replace-tpl (unbound) XReplace an instance of a template. X X@item query-replace-tpl (unbound) XReplace instances of templates, querying for actions on each instance. X@end table X XTemplates may be used in search and replacement operations, similarly to Xregular expressions. There are currently no backward-search operations. XAll of these commands take template names for arguments. So, you will have Xto define any non-standard templates (i.e., any templates not in the Xstandard libraries) before using them. X X@b{Looking-at-tpl} returns @code{t} if @i{point} is immediately followed by Xan instance of the specified template. Otherwise, it returns @code{nil}. X@b{Search-forward-tpl} advances point to the end of the next instance of Xthe named template. If no match is found, point advances to the end of the Xbuffer. The matching algorithm assumes that templates are rectangular, and Xuses indentation for clues in parsing. If the text to be matched differs Xsignificantly in indentation from the template, then the matching algorithm Xmay be fooled or confused. X X@b{Replace-tpl} replaces the source template instance at point with Xa corresponding instance of the object template. XCurrently, the interpretation of ``corresponding'' is: X@itemize @bullet X@item XFor each placeholder in the object template, the first identically-named Xplaceholder from the source template is used. X X@item XIndentation of the text that matches a placeholder is adjusted rigidly to Xits new position. X@end itemize XThe method of parsing templates is quite primitive, but effective. Literal Xcharacters are matched exactly, whitespace is matched loosely, and Xplaceholders are matched by assistance of the user. (The user is asked to Xposition @i{point} at the end of the matching instance.) X X@b{Query-replace-tpl} behaves like @b{query-replace}, except that X@b{search-forward-tpl} and @b{replace-tpl} are used instead of X@b{search-forward} and @b{replace-string}. X X@node aborting, creating, searching, commands X@section Aborting -- how to stop or quit X XIf at any time you wish to abort, type @ctrl{g}. This will stop the Xcurrent command and return you to normal editing. You may use X@i{advertised-undo} (@ctrl{x} u) to restore the buffer to a reasonable Xstate. X XIf you appear to be in a recursive-edit (denoted by @samp{[...]} around Xpart of the mode line), use @b{exit-recursive-edit} (@key{ESC} @ctrl{c}) to Xexit. X X@node creating, , aborting, commands X@section Creating -- how to create your own templates X X@table @code X@item compile-templates (unbound) XStore the templates in a form that allows faster loading. X X@item query-replace-groups (@ctrl{c} @ctrl{t} g) XReplace instances of groups of lines (matched by regular expressions) with Xplaceholders. X X@item query-replace-lines (@ctrl{c} @ctrl{t} l) XReplace lines with placeholders. X X@item region-to-tpl (unbound) XDefine a template, using the current region of text. X X@item replace-line-with-placeholder (@ctrl{c} @ctrl{t} r) XReplace the current line with a placeholder. X X@item replace-region-with-placeholder (@ctrl{c} @ctrl{t} @ctrl{r}) XReplace the current region with a placeholder. X@end table X XOne way to create new templates is with @b{replace-region-with-placeholder} X(@ctrl{c} @ctrl{t} @ctrl{r}) or @b{replace-line-with-placeholder} (@ctrl{c} X@ctrl{t} r). These commands define a new template with the current region Xor line as the template body. You may edit this template by moving to the X@file{new.tpl} buffer (or whatever name you supplied when requested). If Xyou change the template after creating it, you must save the buffer and Xreload the file in order to use the new definition. @b{Region-to-tpl} may Xbe used to begin creation of a template with the current region. X X@b{Query-replace-lines} (@ctrl{c} @ctrl{t} l) and @b{query-replace-groups} X(@ctrl{c} @ctrl{t} g) may be used to iteratively perform the actions of X@b{replace-region-with-placeholder} for lines or groups of lines matching a Xgiven regular expression. These commands are particularly valuable for Xmoving blocks of text as templates. For example, you can replace function Xdefinitions by placeholders with the same names as the functions. Sorting Xthe placeholders and expanding results in a file of functions sorted by Xfunction names. X XSince a template file is just a special ASCII file, you may create it any Xway you wish. There is no need to compile template files. If you do use X@b{compile-templates}, keep in mind that only @b{load-tpl-library} Xunderstands this special form. Compiling templates results in faster Xloading, but no faster generation or expansion. X XA stack of template files is kept for each buffer. So, you may define your Xown personal versions of templates in a file and load them after invoking X@i{template-mode}. The newly loaded versions (your versions) will Xover-ride the previous definitions. There is currently no method available Xfor ``unloading'' template files. X X@node customization, details, commands, top X@chapter Customization of Templates and Their Commands X XOptions for customizing @i{template-mode} fall into four categories: Xcommand behavior, display strings, file names, and template syntax. (See Xthe GNU Emacs Manual for help in modifying options, which are also called X``variables''.) Most @i{template-mode} options are global variables. X X@menu X* behavior:: Options for customizing command behavior X* display:: Special display strings X* files:: Names of files used X* syntax:: Patterns and strings in template definitions X* hooks:: User-defined functions to change behavior X@end menu X X@node behavior, display, customization, customization X@section Behavior -- options for customizing command behavior X XOptions in this category are used to tailor the behavior of template Xgeneration and expansion. X X@table @code X@item tpl-ask-expansion-depth (1) XDepth of recursive placeholder expansions at which to start asking Xwhether to expand. Defaults to 1, which means always ask. X X@item auto-load-new-templates (nil) XOption to automatically load new templates created with X@code{replace-with-placeholder}. Otherwise, @code{load-tpl-file} must be Xused. X X@item auto-save-new-templates (nil) XOption to automatically save new templates created with X@code{replace-with-placeholder}. Otherwise, @code{save-buffer} must be Xused. X X@item tpl-expand-placeholders (t) XTemplate-mode expansion option: if non-nil (default=t), expand placeholders Xafter inserting them. X X@item tpl-fill-while-unscanning (nil) XOption to fill (if auto-fill is turned on) while unscanning (inserting) Xtemplates. Otherwise, templates are inserted as-is. X X@item tpl-form-placeholder-name-from-context (nil) XOption to generate placeholder names by looking for the first symbol after Xpoint. If nil, temporary names are used, instead. (This option is useful Xwhen invoking @code{query-replace-groups}.) X X@item tpl-get-placeholder-name-in-context (t) XOption to allow the user to create placeholder names in context (using X@i{Symbol} mode). Otherwise, temporary names are used. X X@item tpl-include-prefix-in-groups (t) XOption to include the prefix string used to identify groups (when using X@code{query-replace-groups}) in the group. Otherwise, the group begins X@i{after} the identifying prefix string. X X@item tpl-indentation-size (2) XSize of indentation units in columns. X X@item tpl-keep-optional-placeholders (``ask'') XOption to determine processing of optional placeholders in template-mode. XIf t, then always keep them. If nil, then always delete them. If neither Xt nor nil, then always ask. X X@item tpl-literal-whitespace (nil) XOption to preserve leading whitespace when defining new templates. XOtherwise, calculate relative indentation units. X X@item tpl-rebuild-all-templates-template (nil) XOption to rebuild the list of all templates after loading new templates X(including initial loading). Otherwise, the list must be built on demand. X X@item tpl-save-identifier-file (nil) XOption to keep identifier table (created with ``textenter'' placeholders) Xin a file. X X@item tpl-verify-end-of-group (nil) XOption to verify (by positioning @i{point}) the end of each group when Xusing @code{query-replace-groups}. X@end table X X@node display, files, behavior, customization X@section Display -- special display strings X XOptions in this category are used to tailor the appearance of delimiters Xcreated by @i{template-mode}. X X@table @code X@item sym-end-display (``<<'') XDisplay marker after string to be created in symbol mode. X X@item sym-start-display (``>>'') XDisplay marker before string to be created in symbol mode. X X@item tpl-display-begin (``>>'') XDelimiter marking beginning of a selected placeholder. X X@item tpl-display-end (``<<'') XDelimiter marking end of a selected placeholder. X@end table X X@node files, syntax, display, customization X@section Files -- names of files X XOptions in this category consist of file and directory names used by X@i{template-mode}. X X@table @code X@item auto-template-alist (nil) XGlobal list of major modes and their associated template files. It is Xinitialized by @code{tpl-initialize-modes}. X X@item tpl-load-path (nil ...) XA list of directories to search when looking for templates. XNil means look in the current directory. X X@item tpl-new-template-buffer (``new.tpl'') XBuffer containing new templates. X@end table X X@node syntax, hooks, files, customization X@section Syntax -- patterns and strings in template definitions X XOptions in this category consist of regular expressions and strings used to Xdefine templates. There are several options that may be changed, but most Xshould be left alone. Since regular expression search is used quite often, Xone should not use characters that are special to regular expressions in Xdelimiters. For example, the use of @samp{*} in any of the delimiters is Xsure to cause problems. X X@table @code X@item tpl-begin-placeholder (``<'') XRegular expression for beginning of placeholder. X X@item tpl-begin-template-body (``^:begin'') XRegular expression for beginning of template body. X X@item tpl-begin-template-definition (``^Template'') XRegular expression for beginning of template definition. X X@item tpl-destination-symbol (``POINT'') XSpecial placeholder name used as destination of point after expansion. X X@item tpl-end-placeholder (``>'') XRegular expression for end of placeholder. X X@item tpl-end-template-body (``^:end'') XRegular expression for end of template body. X X@item tpl-function-type (``Function'') XName of function-type template type. X X@item tpl-lexical-type (``Lexical'') XName of lexical-type template type. X X@item tpl-next-placeholder-number (1) XCounter used to generate temporary placeholder names. X X@item tpl-pattern-optional (``#'') XRegular expression for optional placeholder delimiter. X X@item tpl-pattern-other (``.'') XRegular expression for all other tokens. X X@item tpl-pattern-placeholder (too complicated to print) XRegular expression for placeholder---built from component parts above. X X@item tpl-pattern-punctuation (``\\s.+'') XRegular expression for at least one punctuation character. X X@item tpl-pattern-string (.*) XRegular expression for each line of string-type templates. X X@item tpl-pattern-symbol (``\$\\sw\\|\\s_\$+'') XRegular expression for at least one symbol character. X X@item tpl-pattern-whitespace (too complicated to print) XRegular expression for at least one whitespace character. X X@item tpl-pattern-word (``\\sw+'') XRegular expression for at least one word character. X X@item tpl-repetition-type (``Repetition'') XName of repetition-type template type. X X@item tpl-selection-type (``Selection'') XName of selection-type template type. X X@item tpl-sep-placeholder (``:'') XRegular expression for separator within placeholder. X X@item tpl-sequence-type (``Sequence'') XName of sequence-type template type. X X@item tpl-string-type (``String'') XName of string-type template type. X X@item tpl-temporary-placeholder-name (``TEMP'') XRoot of temporary placeholder names. X@end table X X@node hooks, , syntax, customization X@section Hooks -- user-defined functions to change behavior X X@table @code X@item sym-check-validity-hook XThis hook may be used to check the validity of expansions of @i{text} and X@i{textenter} placeholders. It is temporarily replaced by an appropriate Xfunction for @i{lexical} placeholders. X X@item template-mode-hook XThis hook is called when @i{template-mode} is turned on. X X@item template-mode-load-hook XThis hook is called when @i{template-mode} is loaded. (Loading includes Xinitialization of the global list of template files to use for different Xmodes. This hook is useful for altering that list.) X X@item template-scan-hook XThis hook is called before attempting to scan for an instance of a Xtemplate. Reformatting with this hook may make it easier to find instances Xof templates. X X@item template-unscan-hook XThis hook is called after unscanning (inserting) a template. Reformatting Xwith this hook may be useful. X@end table X X@node details, appendixa, customization, top X@chapter Details -- Template and Placeholder Syntax X XThis chapter covers all the details of template syntax for those who wish Xto create their own template files. Note that the concrete syntax for Xtemplate definitions may be changed through several user options (e.g., X@code{tpl-begin-template-body}). These options are usually local Xvariables, so that different template files may have different syntax. XHowever, it is best not to modify the syntax of placeholders (even though Xthere are options for doing this), since placeholders usually span template Xfiles. X XA template file consists of a sequence of individual template definitions. XEach definition has the form: X@example XTemplate <template-name> <template-type> X:begin X<template-body> X:end X@end example XNote that the newline at the very end of the template definition is @i{not} Xpart of the template body. The contents and interpretation of the template Xbody differ depending on template type. In general, literal strings in the Xbody stand for themselves. There are no escape characters for including Xspecial characters. X XPlaceholders have a special syntax: X@display X``<'' <placeholder-type> [ : <placeholder-name> ] ``>'' X@end display X(where the square brackets indicate optional parts). Placeholder names are Xusually used to prompt the user for suggestive replacements or context, but Xare especially significant for @code{text} placeholders. Identical X@code{text} placeholders within a template are replaced with the same Xvalue. Two placeholders are identical only if all of their fields are Xidentical, including their names (if present). X@page X X@group XAs mentioned earlier, there are four special forms of placeholders: X@table @code X@item text XMay be replaced by any text not containing a newline. X X@item textenter XSimilar to @code{text}, but saves the result in the identifier completion Xtable. X X@item textlong XMay be replaced by any text, including newlines. X X@item destination (@code{point}) XRepresents the intended final destination of @i{point}. These placeholders Xare always removed from the template body after expanding. X@end table X@end group X X@group XAll other placeholders must define templates. There are six forms of Xtemplates: X@table @code X@item Function XThe result of executing the body of the template (written in GNU XEmacs Lisp) is inserted in place of the placeholder. X X@item Lexical XSimilar to @code{text}, but checks the result against a regular expression. XThe body of the template must be a valid GNU Emacs Lisp regular expression. X X@item Repetition XThese templates must be of the form: ``<separator string> <placeholder>''. XThey result in a series of expansions of ``<placeholder>'', separated by X``<separator string>''s. Note that a newline may be used for the separator. X X@item Selection XThe template body must consist of a list of items of the following form: X@display X``<selection> [ : [ <placeholder> ] ] [ ; comment ]'' X@end display X(where square brackets indicate optional parts). If there is no ``:'', Xthen the ``<selection>'' is considered to be a string replacement for the Xplaceholder. If there is a ``:'' then the item is considered to be a Xreference to another placeholder. In that case, if there is a X``<placeholder>'' it is used for the replacement, otherwise the X``<selection>'' is used. X X@item Sequence XThis type of template may have literal text and/or placeholders in its body. X X@item String XThis type is similar to @code{sequence}, but may not contain placeholders. XIt is parsed more simply (and faster). X@end table X@end group X XThe best method for creating new template files is to start with an Xexisting template file. There are several examples of @code{function} type Xtemplates in the generic template file. Examples of other types are Xpresent in the Emacs-Lisp template file. X X@node appendixa, appendixb, details, top X@appendix Example Templates for Emacs-Lisp X X@example X@group XTemplate arg-type Selection X:begin Xa ; Function name Xb ; Buffer name (must exist) XB ; Buffer name (possibly nonexistent) Xc ; Single character XC ; Command name Xd ; Point as a number (no prompt) XD ; Directory name Xf ; File name (must exist) XF ; File name (possibly nonexistent) Xk ; Keystroke sequence (string) Xm ; Mark as a number (no prompt) Xn ; Number (reads a string and converts) Xp ; Prefix arg converted to number XP ; Prefix arg in raw form Xr ; Region (no prompt) Xs ; String XS ; Symbol Xv ; Variable name (must be user-variable-p) Xx ; Lisp expression unevaluated XX ; Lisp expression evaluated X:end X@end group X X@group XTemplate function Sequence X:begin X X(defun <textenter:function-name> (<text:arguments>) X "<textlong:documentation>" X (interactive "<arg-type><textenter:function-name>: <text:arguments>? ") X ; Local Variables X (let (<text:local-variables>) X ; Body X <stmt:body> X ) ; let X) ; defun <textenter:function-name> X X:end X@end group X X@group XTemplate functions Repetition X:begin X X<function> X:end X@end group X X@group XTemplate package Sequence X:begin X;;; <buffer-name> -- <text:documentation> X;;; <user-full-name>, <today> X X<#variables> X<functions> X:end X@end group X X@group XTemplate stmt Selection X:begin Xprogn: Xcond: Xdebug: Xife: Xif: Xwhile: Xwhilelist: Xsimple: X:end X@end group X X@group XTemplate whilelist Sequence X:begin X(while <text:list> X (setq <text:item> (car <text:list>)) X (setq <text:list> (cdr <text:list>)) X <POINT> X) ; while <text:list> X:end X@end group X X@end example X X@node appendixb, , appendixa, top X@appendix Example Generic Templates X X@example X@group XTemplate buffer-name Function X:begin X(buffer-name) X:end X@end group X X@group XTemplate day Function X:begin X(let ((str (current-time-string))) X (string-match "[0-9]+" str) X (substring str (match-beginning 0) (match-end 0)) X) X:end X@end group X X@group XTemplate month Function X:begin X(let ((str (current-time-string)) X prefix) X (setq prefix (substring str 4 7)) X (cond X ((equal prefix "Jan") X "January") X ((equal prefix "Feb") X "February") X ((equal prefix "Mar") X "March") X ((equal prefix "Apr") X "April") X ((equal prefix "May") X "May") X ((equal prefix "Jun") X "June") X ((equal prefix "Jul") X "July") X ((equal prefix "Aug") X "August") X ((equal prefix "Sep") X "September") X ((equal prefix "Oct") X "October") X ((equal prefix "Nov") X "November") X ((equal prefix "Dec") X "December") X ) X) X:end X@end group X X@group XTemplate today Function X:begin X(concat "<month>" " " "<day>" ", 19" "<year>") X:end X@end group X X@group XTemplate user-full-name Function X:begin X(user-full-name) X:end X@end group X X@group XTemplate year Function X:begin X(substring (current-time-string) -2) X:end X@end group X@end example SHAR_EOF if test 41381 -ne "`wc -c < 'template.texinfo'`" then echo shar: "error transmitting 'template.texinfo'" '(should have been 41381 characters)' fi fi exit 0 # End of shell archive